<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>Icarous: Core Flight Software (cFS) Software Bus Networking (SBN)</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { init_search(); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">Icarous
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.11 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li class="current"><a href="pages.html"><span>Related&#160;Pages</span></a></li>
      <li><a href="modules.html"><span>Modules</span></a></li>
      <li><a href="annotated.html"><span>Classes</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
      </li>
    </ul>
  </div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

</div><!-- top -->
<div class="header">
  <div class="headertitle">
<div class="title">Core Flight Software (cFS) Software Bus Networking (SBN) </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h2>Documentation Version History </h2>
<p>This document details the design and use of the SBN application. This is current as of SBN version 1.10.</p>
<p>This document is maintained by <a href="Christopher.D.Knight@nasa.gov">Chris Knight, NASA Ames Research Center</a>.</p>
<h2>SBN Version History </h2>
<ul>
<li>SBN 1.0 – UDP-only monolithic application.</li>
<li>SBN 1.1 – Added a modular network layer for Spacewire, Serial.</li>
<li>SBN 1.2 @ce1b3ca – TCP module. Merged protocol and data traffic into the same connections/sockets. Heartbeats only sent if no other traffic sent in the last number of seconds. Bug-fix to ensure SBN ignores messages it publishes on the SB, ensures all network messages are big-endian and aligned, removes windowing/retransmit logic.</li>
<li>SBN 1.3 @15f3754 – Removed sync word. Simplified module API, added MID remapping/filtering. Added the (compile-time) option of per-peer tasks for watching pipes and net.</li>
<li>SBN 1.4 @2b6556a – DTN module. Pushed protocol handling (announce/heartbeat) down into the modules that need it (UDP.)</li>
<li>SBN 1.5 @b5cb3d7 – When sending all subs, send them in one message.</li>
<li>SBN 1.6 @b0d0027 – Added “unload” method to modules.</li>
<li>SBN 1.7 @eff7047 – Polling occurs each cycle (modules are responsible for managing timeouts), re-added serial backend, SbnPeerData.dat uses a numeric network ID, not name.</li>
<li>SBN 1.8 @ae9a1f5 - Removed separate housekeeping status structs (moved housekeeping-related values to the main structs (<code><a class="el" href="structSBN__App__t.html" title="SBN global data structure definition. ">SBN_App_t</a></code>, <code><a class="el" href="structSBN__NetInterface__s.html">SBN_NetInterface_s</a></code> (<code>SBN_NetInterface_t</code>), <code><a class="el" href="structSBN__PeerInterface__t.html">SBN_PeerInterface_t</a></code>). standardized on housekeeping being hand-packed big-endian.</li>
<li>SBN 1.9 @063ebf2 - Adds protocol packet to identify protocol version. For now SBN reports if the version matches or not. (Is backward-compatible.) Also modules communicate to the main SBN app when a connection is established and lost and message pipes are only created/maintained for connected peers.</li>
<li>SBN 1.10 - Table-driven configuration, rather than flat-file. Removed net and peer names, instead should always use ProcessorID and NetIdx.</li>
</ul>
<h2>Overview </h2>
<p>SBN is a cFS application that connects the local software bus to one or more other cFS nodes (who are also running SBN) such that all messages sent by an application on one bus will be received by an application on another bus. SBN has a modular <em>network</em> architecture (TCP, UDP, Serial, SpaceWire, etc.) to connect <em>peers</em> and supports multiple peer networks with a local <em>host</em> connection affiliated with each. SBN also remaps and filters messages (cFS table-configured.)</p>
<div class="image">
<img src="SBN_Context.png"  alt="SBN Context"/>
</div>
<h2>SBN Build and Configuration </h2>
<p>SBN is built like any other cFS application, either via specifying it in the the <code>TGT::_APPLISTS</code> parameter in the targets.cmake (for the CMake build) or <code>THE_APPS</code> in the Makefile (for the "classic" build). Protocol modules (<code>sbn_udp</code>, <code>sbn_tcp</code>, <code>sbn_dtn</code>, ...) should also be specified as an application in the build process (and the module should be linked or copied to the apps source directory). SBN must be defined as an application in the <code>cfe_es_startup.scr</code> script but Modules should <em>not</em> be defined there.</p>
<p>SBN uses two tables, the "conf" table for configuring which modules to load and which networks and peers to communicate with and the "remap" table for identifying which Message ID's should be remapped or filtered before sending to specific peers.</p>
<h3>SBN Platform Configuration</h3>
<p>The <code><a class="el" href="sbn__platform__cfg_8h_source.html">sbn_platform_cfg.h</a></code> file contains a number of definitions that control how SBN allocates and limits resources as well as controlling the behavior of SBN. Most "max" definitions relate to in-memory static arrays, so increasing the value increases the memory footprint of SBN (in some cases, non-linearly.)</p>
<h3>SBN Configuration Table</h3>
<p>The SBN configuration table is a standard cFS table defining modules and networks of peers.</p>
<p>See <code><a class="el" href="sbn__tbl_8h_source.html">sbn_tbl.h</a></code> and <code>sbn_conf_tbl.c</code>.</p>
<h3>SBN Remapping Table</h3>
<p>The SBN remapping table is a standard cFS table defining, on a peer-by-peer basis, which message ID's should be remapped to other ID's, or which message ID's should be filtered (where the "To" field is 0).</p>
<p>See <code><a class="el" href="sbn__tbl_8h_source.html">sbn_tbl.h</a></code> and <code>sbn_remap_tbl.c</code>.</p>
<h2>SBN Remapping and Filtering </h2>
<p>In complex SBN peer networks, it may be useful to have each node have its own configuration of message ID's that local apps publish and subscribe to, and to limit traffic between the nodes or map from one ID space to another. SBN supports this via the remapping and filtering capability, which can be configured both by the remap table at initialization time and via commands at runtime.</p>
<p>The SBN remapping subsystem, by default, does not affect traffic and all messages published on one node is sent to any peers that have subscribed to that ID. Alternatively, SBN remapping can be configured so that ONLY those entries that are remapped are sent to peers; and, yes, you can remap from an MID to the same MID.</p>
<p>SBN remapping may be enabled at start time via a compile-time macro, and can be enabled and disabled at runtime via the remapping configuration command.</p>
<h2>SBN Control Commands </h2>
<p>SBN has a number of commands for managing the SBN application's configuration and for requesting housekeeping telemetry.</p>
<table class="doxtable">
<tr>
<th>Macro </th><th>CC </th><th>Command Description </th><th>Parameters  </th></tr>
<tr>
<td><code>SBN_NOOP_CC</code> </td><td><code>0x00</code></td><td>Do nothing beyond reporting an event. </td><td>&lt;none&gt; </td></tr>
<tr>
<td><code>SBN_RESET_CC</code> </td><td><code>0x01</code></td><td>Resets the SBN network. </td><td>&lt;none&gt; </td></tr>
<tr>
<td><code>SBN_RESET_PEER_CC</code> </td><td><code>0x02</code></td><td>Resets a connection to a particular peer. </td><td><code>uint8 NetIdx, uint8 PeerIdx</code> </td></tr>
<tr>
<td><code>SBN_REMAPCFG_CC</code> </td><td><code>0x05</code></td><td>Sets the remapping configuration. </td><td><code>uint8 Enabled, uint8 RemapDefaultFlag</code> </td></tr>
<tr>
<td><code>SBN_REMAPADD_CC</code> </td><td><code>0x06</code></td><td>Adds a remapping. </td><td><code>uint32 ProcessorID, CFE_SB_MsgId_t FromMID, CFE_SB_MsgId_t ToMID</code> </td></tr>
<tr>
<td><code>SBN_REMAPDEL_CC</code> </td><td><code>0x07</code></td><td>Removes a remapping. </td><td><code>uint32 ProcessorID, CFE_SB_MsgId_t FromMID</code> </td></tr>
<tr>
<td><code>SBN_HK_CC</code> </td><td><code>0x0A</code></td><td>Requests main housekeeping telemetry. </td><td>&lt;none&gt; </td></tr>
<tr>
<td><code>SBN_HK_NET_CC</code> </td><td><code>0x0B</code></td><td>Requests housekeeping telemetry for a net. </td><td><code>uint8 NetIdx</code> </td></tr>
<tr>
<td><code>SBN_HK_PEER_CC</code> </td><td><code>0x0C</code></td><td>Requests housekeeping telemetry for a peer.</td><td><code>uint8 NetIdx, uint8 PeerIdx</code> </td></tr>
<tr>
<td><code>SBN_HK_PEERSUBS_CC</code></td><td><code>0x0D</code></td><td>Requests hk telemetry for a peer's subs. </td><td><code>uint8 NetIdx, uint8 PeerIdx</code> </td></tr>
<tr>
<td><code>SBN_HK_MYSUBS_CC</code> </td><td><code>0x0E</code></td><td>Requests hk telemetry for my subs. </td><td>&lt;none&gt; </td></tr>
</table>
<h2>SBN Housekeeping Telemetry </h2>
<p>Housekeeping command codes are used to request housekeeping telemetry messages. As all housekeeping is requested with command codes to the main (and only) command MID, the command code used to request the housekeeping is returned in the housekeeping payload so that they can be differentiated. All numeric values are transmitted in big-endian order and no padding is used.</p>
<p>The following commands generate payloads in the following format:</p>
<p><em>SBN_HK_CC</em></p>
<table class="doxtable">
<tr>
<th>Field </th><th>Type </th><th>Description  </th></tr>
<tr>
<td><code>CC</code> </td><td><code>uint8</code> </td><td>Command code of HK request. </td></tr>
<tr>
<td><code>CmdCnt</code> </td><td><code>uint16</code></td><td>Number of commands received. </td></tr>
<tr>
<td><code>CmdErrCnt</code></td><td><code>uint16</code></td><td>Number of commands that generated errors. </td></tr>
<tr>
<td><code>SubCnt</code> </td><td><code>uint16</code></td><td>Number of local subscriptions. </td></tr>
<tr>
<td><code>NetCnt</code> </td><td><code>uint16</code></td><td>Number of networks configured. </td></tr>
</table>
<p><em>SBN_HK_NET_CC</em></p>
<table class="doxtable">
<tr>
<th>Field </th><th>Type </th><th>Description  </th></tr>
<tr>
<td><code>CC</code> </td><td><code>uint8</code> </td><td>Command code of HK request. </td></tr>
<tr>
<td><code>ProtocolID</code></td><td><code>uint8</code> </td><td>The ID of the protocol of this network. </td></tr>
<tr>
<td><code>PeerCnt</code> </td><td><code>uint16</code> </td><td>The number of peers associated with this network. </td></tr>
</table>
<p><em>SBN_HK_PEER_CC</em></p>
<table class="doxtable">
<tr>
<th>Field </th><th>Type </th><th>Description  </th></tr>
<tr>
<td><code>CC</code> </td><td><code>uint8</code> </td><td>Command code of HK request. </td></tr>
<tr>
<td><code>QoS</code> </td><td><code>CFE_SB_Qos_t</code> </td><td>QoS flags for this peer. </td></tr>
<tr>
<td><code>SubCnt</code> </td><td><code>uint16</code> </td><td>Number of errors generated in trying to receive from this peer. </td></tr>
<tr>
<td><code>ProcessorID</code></td><td><code>uint32</code> </td><td>The ProcessorID of the peer. </td></tr>
<tr>
<td><code>LastSend</code> </td><td><code>OS_time_t</code> </td><td>The last time I sent a message to this peer. </td></tr>
<tr>
<td><code>LastRecv</code> </td><td><code>OS_time_t</code> </td><td>The last time I received a message from this peer. </td></tr>
<tr>
<td><code>SendCnt</code> </td><td><code>uint16</code> </td><td>Number of messages sent to this peer. </td></tr>
<tr>
<td><code>RecvCnt</code> </td><td><code>uint16</code> </td><td>Number of messages received from this peer. </td></tr>
<tr>
<td><code>SendErrCnt</code> </td><td><code>uint16</code> </td><td>Number of errors generated in trying to send to this peer. </td></tr>
<tr>
<td><code>RecvErrCnt</code> </td><td><code>uint16</code> </td><td>Number of errors generated in trying to receive from this peer. </td></tr>
</table>
<p><em>SBN_HK_PEERSUBS_CC</em></p>
<table class="doxtable">
<tr>
<th>Field </th><th>Type </th><th>Description  </th></tr>
<tr>
<td><code>CC</code> </td><td><code>uint8</code> </td><td>Command code of HK request. </td></tr>
<tr>
<td><code>PeerIdx</code> </td><td><code>uint16</code> </td><td>Index of the peer in the request. </td></tr>
<tr>
<td><code>SubCnt</code> </td><td><code>uint16</code> </td><td>Number of local subscriptions. </td></tr>
<tr>
<td><code>Subs</code> </td><td><code>CFE_SB_MsgId_t[SubCnt]</code></td><td>Subscriptions. </td></tr>
</table>
<p><em>SBN_HK_MYSUBS_CC</em></p>
<table class="doxtable">
<tr>
<th>Field </th><th>Type </th><th>Description  </th></tr>
<tr>
<td><code>CC</code> </td><td><code>uint8</code> </td><td>Command code of HK request. </td></tr>
<tr>
<td><code>SubCnt</code> </td><td><code>uint16</code> </td><td>Number of local subscriptions. </td></tr>
<tr>
<td><code>Subs</code> </td><td><code>CFE_SB_MsgId_t[SubCnt]</code></td><td>Subscriptions. </td></tr>
</table>
<h2>SBN Interactions With the Software Bus (SB) </h2>
<p>SBN treats all nodes as peers and (by default) all subscriptions of local applications should receive messages sent by publishers on other peers, and all messages published on the local bus should be transmitted to any peers who have applications subscribed to that message ID.</p>
<div class="image">
<img src="SBN_DataMsgProc.png"  alt="SBN Data Message Processing"/>
</div>
<p>The Software Bus (SB), when an application subscribes to a message ID or unsubscribes from a message ID, sends a message that SBN receives. Upon receipt of these messages, SBN updates its internal state tables and sends a message to the peers with the information on the update.</p>
<div class="image">
<img src="SBN_SB_Interface.png"  alt="SBN-SB Interface"/>
</div>
<h2>SBN Application-Level Network Protocol </h2>
<p>In communicating with peers over a network protocol provided by a protocol module, SBN uses an SBN message format which is comprised of the following fields in big-endian, packed (no alignment) format:</p>
<table class="doxtable">
<tr>
<th>Field </th><th>Type </th><th>Description  </th></tr>
<tr>
<td><code>MsgSz</code> </td><td><code>uint16</code></td><td>The total size of the message, including this header. </td></tr>
<tr>
<td><code>MsgType</code></td><td><code>uint8</code> </td><td>The type of the message (see below). </td></tr>
<tr>
<td><code>CpuID</code> </td><td><code>uint32</code></td><td>The ProcessorID of the sender. </td></tr>
</table>
<p>Message types are an enumeration from below, although protocol modules may send additional message types. Type values of 128 or higher (high bit set) are reserved for module use.</p>
<table class="doxtable">
<tr>
<th>MsgType </th><th>Value </th><th>Description  </th></tr>
<tr>
<td><code>SBN_NO_MSG</code> </td><td><code>0x00</code></td><td>No payload. (Unused.) </td></tr>
<tr>
<td><code>SBN_SUB_MSG</code> </td><td><code>0x01</code></td><td>Payload is local subs for peer to add. </td></tr>
<tr>
<td><code>SBN_UNSUB_MSG</code></td><td><code>0x02</code></td><td>Payload is local unsubscriptions for peer to remove. </td></tr>
<tr>
<td><code>SBN_APP_MSG</code> </td><td><code>0x03</code></td><td>Payload is a message from the local software bus. </td></tr>
<tr>
<td><code>SBN_PROTO_MSG</code></td><td><code>0x04</code></td><td>Payload is a protocol informational packet. </td></tr>
</table>
<p>Currently protocol messages contain a single byte value representing the current protocol version defined by <code>SBN_PROTO_VER</code>.</p>
<h2>SBN Scheduling and Tasks </h2>
<p>SBN has two modes of operation (configured at compile time):</p>
<ul>
<li>A traditional scheduler (SCH)-driven mode where SCH sends a wakeup message periodically and SBN polls pipes and network modules. SBN has a built-in timeout period so that if SCH is somehow not functioning properly, or is mis-configured, SBN will continue to function. This mode is preferable in environments where resources are constrained, where network traffic load is well understood, and deterministic behavior is expected.</li>
<li>A per-peer task model where the local SBN instance creates two tasks for every peer&ndash;one task blocks on reading the local pipe (waiting for messages to send to the respective peer) and the other task blocks on the network module's "receive" function, waiting for messages from the peer to send to the local bus. This model is preferred in environments where network traffic load may vary significantly (posing a risk of overloading pipes), and where determinism is not expected and resources are not particularly constrained.</li>
</ul>
<p>Technically, the choice of task or SCH-driven processing is set for each direction ("sending" local bus messages to the peer and "receiving" messages from the peer to put on the local bus.) However, it's generally best to stick with either SCH-driven processing or task-driven processing.</p>
<h2>SBN Protocol Modules </h2>
<p>SBN requires the use of protocol modules&ndash;shared libraries that provide a defined set of functions to send and receive encapsulated software bus messages and subscription updates. Protocol modules may use connection-less (UDP) or connection-based (TCP) network technologies and network reliability and connection maintenance is expected to be provided by the module or the network technology it is using. SBN does benefit from knowing when a peer is "connected" so that the local subscriptions can be sent (in bulk) to that peer; otherwise SBN does not need to know the state of the network the module is communicating with.</p>
<p>SBN modules are built as separate cFS "applications" but are not loaded via the Executive Service (ES) interface, instead the module's shared library is loaded by the SBN application (as defined by a start-time configuration file.)</p>
<p>Currently SBN provides the following modules:</p><ul>
<li>UDP - Utilizing the UDP/IP connectionless protocol, the UDP module uses "announce" and "heartbeat" internal messages to determine when a peer has connected to the network (and that the subscriptions need to be sent.) Otherwise no network reliability is provided by the UDP module, packets may be lost or jumbled without the knowledge of SBN.</li>
<li>TCP - The TCP module utilizes the Internet-standard, high reliability TCP protocol, which provides for error correction and connection management.</li>
<li>DTN - Integrating the ION-DTN 3.6.0 libraries, the DTN module provides high reliability, multi-path transmission, and queueing. Effectively, DTN peers are always connected.</li>
<li>Serial - Supports SBN over standard serial devices.</li>
</ul>
<h2>SBN Datastructures </h2>
<p>SBN utilizes a complex set of data structures in memory to track the state of the local system and its state knowledge of the peers on the network.</p>
<div class="image">
<img src="SBN.png"  alt="SBN Data Structures"/>
</div>
 </div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.11
</small></address>
</body>
</html>
